ATSULeftwardCursorPosition

OSStatus ATSULeftwardCursorPosition (
                     ATSUTextLayout iTextLayout,
                     UniCharArrayOffset iOldOffset,
                     ATSUCursorMovementType iMovementType,
                     UniCharArrayOffset *oNewOffset);

iTextLayout

A reference of type ATSUTextLayout. Pass a reference to an initialized text layout object. You cannot pass NULL for this parameter.

iOldOffset

A value of type UniCharArrayOffset. Pass the edge offset corresponding to the initial cursor position. To indicate the beginning of the text buffer, pass the constant kATSUFromTextBeginning, described in Text Offset Constant. If the edge offset is outside the text buffer, ATSULeftwardCursorPosition returns the result code kATSUInvalidTextRangeErr.

iMovementType

A value of type ATSUCursorMovementType. Pass the unit distance that the cursor was moved. See Cursor Movement Constants for a description of possible values. You must pass a value between 2 bytes and a word in length.

oNewOffset

A pointer to a value of type UniCharArrayOffset. On return, the edge offset corresponding to the new cursor position. This offset may be outside the text buffer.

function result

A result code. The result code kATSUInvalidCacheErr indicates that an attempt was made to read in styled data from an invalid cache. In this case, either the format of the cached data does not match that used by ATSUI or the cached data is corrupt. The result code kATSUQuickDrawTextErr indicates that the QuickDraw function DrawText encountered an error while measuring a line of text. For a list of other ATSUI-specific result codes, see Result Codes.

DISCUSSION

The ATSULeftwardCursorPosition function determines the edge offset in backing store memory corresponding to the left of the high caret position based on the type of cursor movement specified in the iMovementType parameter. You should call ATSULeftwardCursorPosition and the function ATSURightwardCursorPosition when the initial edge offset is at a line boundary. At a line boundary, the caret is split into a high and low caret. If the initial edge offset is not at a line direction boundary, you should instead call the functions ATSUNextCursorPosition and ATSUPreviousCursorPosition to calculate the next and previous cursor positions.

Note that you may not be able to move the cursor 2-bytes, since doing so might place the cursor in the middle of a surrogate pair.

Except in the case of Indic text (and other cases where the font rearranges the glyphs), for left-to-right text, ATSULeftwardCursorPosition has the same effect as calling ATSUPreviousCursorPosition. For right-to-left text, ATSULeftwardCursorPosition has the same effect as calling ATSUNextCursorPosition.

SPECIAL CONSIDERATIONS

ATSULeftwardCursorPosition may allocate memory in your application heap, unless you designate a different heap by calling the function ATSUCreateMemorySetting.

VERSION NOTES

Available beginning with ATSUI 1.0.